The portal schema (formerly Docserv product schema) got some updates.

General Changes

These changes reflect broad architectural shifts and naming conventions throughout the entire configuration system.

• Rebranding: The naming convention has shifted from "Docserv²" to "Portal."

• Enhanced Modularity: The schema now explicitly supports splitting large configuration files into smaller, more manageable parts. By utilizing inclusion mechanisms, you can maintain different sections of the portal (like <categories> or specific products) in separate files, leading to a cleaner and more maintainable structure.

• Documentation-First Design: The schema now heavily utilizes db:refname and db:refpurpose annotations for almost every element and attribute. This allows for automated generation of human-readable documentation directly from the RNC file.

• Implicit Language Logic: Master/source language identification has shifted from a boolean attribute (@default) to a value-based system. The schema now assumes en-us is the default language for products and deliverables.

• Migration Tooling: To facilitate the transition, an XSLT migration stylesheet is available. This tool automates the conversion of version 6.0 configuration files to the 7.0 format, handling the renaming of elements, restructuring of attributes, and the removal of deprecated metadata.

• Resolving Ambiguity: Some elements were used in multiple contexts, for example, the multipurpose <language> element. The new portal schema resolves this ambiguity.

New Elements and Attributes

Version 7.0 introduces several elements to support a more hierarchical portal structure and better metadata documentation.

Elements

• <portal>: The new root element for the entire portal configuration.
• <spotlight>: Used to highlight specific products or deliverables on the entry page.
• <productfamilies>: A container for defining product family groupings.
• <series>: Defines series/tabs (e.g., SBP, TRD, Products & Solutions).
• <item>: Generic element for entries within a family or series.
• <descriptions>: A unified wrapper for product or version descriptions.
• <categories>: A wrapper for grouping category definitions.
• <resources>: Replaces the old builddocs logic for defining deliverables.
• <prebuilt>: Specifically for defining pre-built content links with metadata.
• <xi:include>: An XInclude element pointing to an external XML resource to facilitate modularity.

Attributes

• @schemaversion: Replaces the previous versioning logic for stricter validation against the 7.0 spec.
• @rank: Determines the sorting order of products on the portal homepage.
• @family: Links a product to a specific product family via IDREF.
• @series: Links a product to a specific series/tab via IDREF.
• @path: Used on products and docsets to specify relative directory names.
• @linkend: Used in <ref\> elements to point to external link identifiers.
• @treatment: Defines how version-specific descriptions interact with global ones (append, prepend, or replace).

Renamed Elements and Attributes

Many elements were renamed to move away from "Docserv²" terminology and adopt a cleaner "Portal" naming convention.

Removed Elements and Attributes

The following items were deprecated or removed to simplify the build process and clean up the configuration.

• <buildcontainer>: Support for specifying custom Docker images per version has been removed.
• <param>: Support for custom XSLT parameters via the config file is removed.
• @translation-type: The distinction between "list" and "full" translations has been replaced by a more flexible <locale> and reference model.
• @default: This attribute (previously used in <desc> and <language> to flag the source/master language) has been removed. Language master ship is now determined by the explicit en-us value in the @lang attribute.
• @meta from <deliverable>

Changed Content Models

The structure of the schema has evolved to be more modular and better documented.

Modularization (XInclude)

Major elements now support xi:include, allowing configuration files to be broken into smaller, manageable chunks.

link

Allows multiple URLs in <link>. This makes it possible to have different formats. Additionally allow a <desc> element to describe the resource.

The minimum structure is this:

<external>
    <link category="about" gated="false">
      <!-- Cardinality for <url>: one or more -->
      <url href="http://example.com" format="html"/>
      <descriptions>
    <desc lang="en-us">
      <title></title>
    </desc>
    <!-- more <desc> for other languages -->
      </descriptions>
    </link>
</external>

Deliverable References

In version 7.0, translations of deliverables are primarily handled as references (<ref\>) back to the source DC file in the en-us locale, rather than duplicating the full deliverable metadata.

Additionally, the <ref/> contains only a @linkend attribute to link to a resource. You don't need dc, product, or other strange combinations anymore.

Expanded Root Element Support

The schema no longer restricts the start of a document to just a product definition. It now allows for much more variety in valid root elements, supporting the standalone definition of <product>s, <docset>s, <categories>, and more.

Simplified External Link Model

The model for external links has been significantly flattened. The previous hierarchical structure involving nested <language> elements has been removed. Now, a <link> directly contains a list of <url> elements and a unified <descriptions> block, simplifying how external resources are defined across different locales.

References

• Based on https://confluence.suse.com/x/0QB5e